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1.  Introduction 


CsvtoZdata  is  a  translator  that  converts  a  comma-separated  value  format  file  into  a  “Z-data” 
ASCII  (American  standard  code  for  information  exchange)  format.  Z-data  files,  which  are  used 
to  share  a  warhead’s  fragmentation  patterns,  are  used  by  a  number  of  U.S.  Army  analytical  tools 
directly  or  in  conjunction  with  a  separate  pre-processing  tool. 

The  Csv  to  Zdata  tool  is  designed  to  translate  fragmentation  pattern  information  for  use  in  the 
Casualty  Reduction  (CASRED)  model.  CASRED  is  a  U.S.  Army  item-level  lethality  and 
survivability  perfonnance  model  that  calculates  the  probability  of  personnel  incapacitation  ( 1 ).  The 
U.S.  Army  Research  Laboratory  has  created  a  number  of  pre-  and  post-processing  software  tools  to 
supplement  CASRED  and  allow  it  to  be  interfaced  with  other  simulations1.  One  of  the  pre¬ 
processing  tools  is  “ZdatatoCASRED”  which  translates  nonnal  Z-data  files  into  fragmentation 
pattern  files  that  can  be  directly  entered  into  CASRED.  The  output  of  Csv  to  Zdata  will  be  the 
input  for  Zdata  to  CASRED  which  in  turn  will  produce  a  file  that  will  be  used  directly  by 
CASRED.  This  document  describes  Csv  to  Zdata,  its  options,  and  input  but  does  not  address 
CASRED. 


Figure  1  portrays  the  translation  sequence.  The  fragmentation  profile  is  stored  as  a  spreadsheet  in 
the  Excel2  format.  This  spreadsheet  and  its  fields  are  described  later  in  detail.  The  spreadsheet 
must  first  be  exported  into  the  comma-separated  value  (csv)  format  (2).  This  can  be  accomplished 
with  the  “save  as”  feature  common  to  many  spreadsheet  applications.  In  the  figure  1  final 
sequence,  Csv  to  Zdata  translates  the  .csv  format  to  the  Z-data  fixed  field  length  format. 
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Figure  1.  Where  Csv  to  Zdata  fits  in  the  translation  process. 


'  The  particular  CASRED  tool  that  uses  the  Z-data  file  is  called  ZdatatoCASREDMetric. 
“Excel  is  a  trademark  of  Microsoft. 
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2.  The  Excel  Fragmentation  File 


This  section  provides  a  detailed  explanation  of  the  fragmentation  file  and  its  logical  fields.  The 
fragmentation  profile  describes  fragment  mass  and  velocity  distributions  following  a  munition 
detonation.  Targets  may  be  placed  about  the  point  of  detonation  to  detennine  probability  of 
damage  as  in  figure  2. 


Figure  2.  Blast  fragmentation  profile 
describes  blast  fragments. 

Conceptually,  the  fragments  are  described  in  angular  segments  about  the  point  on  the  ground  directly 
below  the  detonation  point,  known  as  ground  zero  (GZ).  The  angular  segments  are  measured  about 
the  GZ  in  the  ground  plane  from  the  long  axis  of  the  warhead.  Angles  are  measured  from  zero 
degrees  at  the  front  of  the  warhead  around  to  180  degrees  at  the  rear.  The  angular  segments  pictured 
in  figure  3  are  shown  in  five  5-degree  intervals.  The  actual  segment  intervals  could  be  any  angle  and 
do  not  have  to  be  equally  spaced.  The  fragment  data  only  span  180  degrees  since  the  remaining 
fragment  profile  (as  high  as  360  degrees)  is  assumed  to  be  symmetric. 


Figure  3.  Angular  segments  from  blast  center. 
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2.1  Excel  File  Overview 


Viewed  with  a  spreadsheet  application,  the  .xls  fragmentation  file  might  appear  similar  to  the  file 
seen  in  figure  4.  The  first  row  contains  text  headers  for  each  column  (e.g.,  “X.  1”,  “X.2”,  and  so 
on  for  every  column  in  the  file  that  contains  data).  This  header  row  has  no  meaning  to  the 
context  of  the  data  but  must  be  present.  The  number  of  angular  segments  (in  this  case,  36)  is 
identified  in  row  2  of  column  A. 
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Figure  4.  Angular  segments  in  the  spreadsheet. 


2.2  Angular  Segments  in  the  Excel  File 

Each  angular  segment  starts  with  a  header  row  as  shown  in  figure  5.  In  this  figure,  the  fifth 
angular  segment  header  is  highlighted  (on  row  7  of  the  spreadsheet).  The  header  defines  the 
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segment’s  lower,  upper,  and  average  angle  (the  first  three  numbers).  The  next  three  numbers 
define  the  fragment  velocities  at  the  beginning,  end,  and  center  of  this  angular  segment. 

The  last  number  in  the  header  row  (seen  in  column  G)  defines  the  number  of  weight  classes  to 
follow  the  header  row.  Note  that  the  first  4  angular  segments  (rows  3  through  6)  contained  zero 
weight  classes,  i.e.,  no  fragments  were  found  in  those  angular  zones.  The  first  row  following  the 
header  defines  the  series  of  weight  classes  used  to  describe  the  fragments  in  this  angular  segment. 
The  next  row  gives  the  average  number  of  fragments  in  each  of  the  weight  classes. 


Figure  5.  A  highlighted  angular  segment  record  header. 

Examining  figure  5,  we  see  that  the  20-  to  25-degree  angular  segment  header  is  identified  on 
spreadsheet  row  7.  Two  weight  classes  are  identified  in  column  G  of  row  7. 

For  example,  in  rows  8  and  9,  we  see  that  column  A  holds  the  first  weight  class.  This  class  has 
an  average  of  0.03  fragment  that  is  in  the  1.55-grain  weight  class.  The  second  weight  class  is 
seen  in  column  B  where  we  see  0.04  mean  fragment  in  the  1.65-grain  weight  class. 

2.3  The  Shaping  Factor 

A  shaping  factor  follows  in  the  next  row  immediately  after  the  data  for  the  last  angular  segment. 
Shape  factor  defines  the  relationship  between  the  fragments’  area  and  weight  averaged  over  a 
representative  sample  of  warhead  fragments.  The  definition  of  shape  factor  and  a  description  of 
how  it  is  computed  are  given  in  Army  FM101-51-3,  Joint  Munitions  Effective  Manual,  Testing 
and  Data  Reduction  Procedure  for  High-Explosive  Munitions,  chapter  2  (3). 

The  shape  factor  is  a  single  number  in  column  A.  It  is  found  in  the  next  spreadsheet  row 
following  the  last  angular  segment  record.  Its  units  by  default  are  in  square  feet  one  third  power 
grains  per  pound 

ft 2  ■  \J  grains  ^ 
pounds 

The  shaping  factor  may  be  optionally  converted  to  grains  per  cubic  inch: 
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^  grains  ' 

V  in3  J 

via  the  SHAPING  FACTOR  CONVERT  configuration  file  option,  as  described  in  the 
configuration  file  description  (section  6). 


3.  The  CSV  and  Excel  Fragmentation  File  Schema 


Figure  6  is  a  condensed  description  of  the  fragmentation  file  schema.  The  descriptions  and  fields 
are  the  same  for  both  file  formats  (excel  and  the  .csv  files). 


Fragmentation  File:  FRAGHEADER  *  FRAGBODY 

FRAGHEADER:  1-row  of  L  text  fields 

FRAGBODY : 

(N:  the  number  of  angular  segments) 
{angular  segment  record  1  } 

{  angular  segment  record  2  } 

{  angular  segment  record  3  } 

{  angular  segment  record  N  } 
(shaping  factor) 


angular  segment  record: 

(  angular  segment  header  ) 

(  weight  classes  ) 

angular  segment  header: 

min  angle,  max  angle,  avg  angle,  begin  velocity,  end  velocity,  center,  velocity,  M:  the 
number  of  weight  classes  (M  <=  L) 

weight  classes: 

weight  class  1,  weight  class  2,  ...  weight  class  M. 

Avg  frags  in  class  1,  Avg  frags  in  class  2,  ...  Avg  frags  in  class  M. 

shaping  factor: 
number 


Figure  6.  Fragmentation  file  format  description. 


4.  Csv  to  Zdata  the  Translator 


CsvtoZdata  can  be  used  to  convert  an  Excel  fragmentation  file  into  a  Z-data  file.  The  Excel 
spreadsheet  file  must  first  be  converted  to  a  comma-separated  values  fonnat  file  (.csv)  by  the 
“save  as”  feature  common  to  many  spreadsheet  applications.  Csv  to  Zdata  can  then  understand 
the  fragmentation  file  fields  and  generate  a  Z-data  file.  This  process  is  portrayed  in  figure  1 . 
Figure  7  displays  how  the  spreadsheet  shown  in  figure  4  would  appear  after  it  has  been  saved  as 
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a  .csv  file  when  viewed  with  a  standard  text  editor.  This  divides  the  spreadsheet  columns  into 
comma-separated  ASCII  fields  (2). 


Session  Edit  View  Bookmarks  Settings  Help 


M  >  M  M  M 


I  f  I  I  f  I  I 


"X. 1" , "X . 2" , "X . 3" , "X . 4" , "X^5" , "X . 6" , "X. 7" , "X. 8" , "X . 9" , "X. 10" , "X . 11" , "X . 12" , "X . 13" , "X . 14" , "X . 15" 

36 iipiiitiitiiiiiiiiii 

0,5,2. 5, 0,0, 0,0, , , , , , , 
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10,15,12.5,0,0,0,0, , , 

15,20,17.5,0,0,1293.55403938858,0 . 

20,25,22.5, 1293 . 55403938858 , 2587 . 10807877715 , 2570 . 71245982086 ,2 . 

0 . 0272637557541932 ! 6 ! 036677104035983 . 

25,30,27.5 ,2570.71245982086 ,2554.31684086456 , 2558 . 59176756262 ,14 . 

0.25,0.35,0.45,0.55,0.65,1.05,1.15,1.25,1.35,1.45,1.55,1.65,1.75,3 . 

0 . 131325197087032 , 0 . 0922049225309656 , 0 . 0637423016176277 ,0.0434689358853011,0.0299638587525028 , 0 

30,35,32.5,2558. 59176756262 , 2562 . 86669426067 , 2530 . 84078230365 , 11 . 

0.25,0.35,0.45,1.15,1.25,1.35,1.45,1.55,1.65,1.75,3 . 

0 . 06899170376707 , 0 . 0484398641100  552,0.033487023725692,0. 029401347662476 ,0.045773  5816044099 ,0.07: 

35,40,37.5,2530.84078230365,2498. 81487034663 ,2297.87227574392,24 . 

0.25.0.35.0.45.0.55.0.65.0.75.0.85.0.95.1.05.1.15.1.25.1.35.1.45.1.55.1.65.1.75.1.85.1.95.2.05. 


Figure  7.  Fragmentation  file  in  .csv  format. 


4.1  Compiling  CsvtoZdata 

To  compile  the  program,  simply  move  to  the  Csv  to  Zdata  directory  and  execute  the  “make” 
utility  from  the  command  line.  The  Csv_to_Zdata.exe  executable  program  will  be  created. 

Csv  to  Zdata  is  written  in  standard  C  and  developed  on  the  Linux  operating  system.  The  main 
directory  hierarchy  is  displayed  in  figure  8.  When  the  source  code  is  compiled,  a  GNU3 
“makefile”  uses  this  directory  organization  to  first  create  the  support  libraries  (in  libsrc).  The 
CommaDelim  subdirectory  holds  the  source  code  for  the  “cdf’  library.  This  library  is  described 
further  in  appendix  A.  Scanner  holds  a  text  input  scanning  library.  Csv  to  Zdata’s  source  code  is 
located  in  the  main  Csv  to  Zdata  directory.  The  library  functions  of  scanner  and  cdf  have  been 
previously  documented  ( 4 ).  Documentation  for  them  is  also  available  on  line  under  their 
subdirectories.  The  Csv_to_Zdata  function  calls  have  been  documented  with  Doxygen4  (5). 


-Cs  u  _t  o  _Zdat  a 

- doc 

- inc lude 

- lib 

- libsrc 

- ComnaDe lin 

- Saf  ePrint 

- Scanner 


Figure  8.  Csv  to  Zdata  software 
directory  organization. 


3GNU  =  GNU,  not  Unix 

4Doxygen  is  a  software  documentation  system  for  C++,  C,  Java  and  other  languages.  It  is  used  much  like  the 
documentation  system  distributed  with  the  Java  programming  language  called  Javadoc.  Comments  may  contain 
“tags”  directly  in  the  code.  These  tags  are  used  to  auto-generate  some  of  the  software  documentation.  (Java  is  a 
registered  trademark  of  Sun  Microsystems.) 
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Doxygen  auto-generated  descriptions  of  these  function  calls  are  also  available  on  line  and  may 
be  viewed  in  the  “doc”  subdirectory  (Csv_to_Zdata/doc/html/index.html)  via  a  standard  web 
browser. 

4.2  Running  CsvtoZdata  Interactively 

Cvs_to_Zdata.exe  is  a  command  line  application  that  may  be  run  interactively  or  in  batch  mode. 

If  no  command  line  options  are  provided,  then  by  default,  the  program  runs  interactively, 
querying  the  user  for  input  that  determines  the  configuration  of  parameters  for  the  translation. 

4.3  Running  Csv  to  Zdata  in  Batch  Mode 

Usage:  . /Csv_to_Zdata . exe  [-c  Conf iguration_File  ]  \ 

[  -i  InputFile . csv  ]  [  -o  OutputFile . ZDATA  ] 

In  the  author’s  opinion,  it  is  much  easier  to  edit  preferences  in  the  configuration  file  (see  section  6) 
with  a  spreadsheet  application  and  then  run  Csv  to  Zdata  in  batch  mode.  In  batch  mode,  the 
command  line  options  seen  above  are 

•  -c  Configuration  File 

•  -i  InputFile. csv 

•  -o  OutputFile.  ZD  AT  A 
in  which 

ConfigurationFile  is  the  name  of  a  configuration  file  that  controls  how  Csv  to  Zdata  translates 
the  fragmentation  file. 

InputFile.csv  is  the  name  of  the  Excel  fragmentation  profile  spreadsheet  that  has  been  saved  as  a 
.csv  file. 

OutputFile.ZDATA  is  the  name  you  choose  for  your  fragmentation  file  translated  into  ZDATA 
format. 


5.  Translation  Rules 


With  a  few  exceptions,  the  program  essentially  takes  the  .csv  fields  and  converts  them  to  a  fixed 
length  floating  point  format  that  is  understood  by  the  FORTRAN  (Formula  Translator)  language 
used  to  code  CASRED.  The  exceptions  are  the  optional  conversions  alluded  to  and  some  minor 
rules: 

1 .  When  there  are  no  weight  classes  following  an  angular  segment  record  header,  at  least  one 
class  is  inserted  into  the  output  file  anyhow.  This  is  because  the  FORTRAN  source  expects  to 
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see  at  least  one  class.  In  this  case,  the  class  contains  zero  fragments  and  has  no  effect  on  the 
CASRED  output. 

2.  The  mass  of  pentolite  that  would  have  the  same  blast  effects  as  the  warhead  is  the  last  number 
in  the  file.  The  ability  of  CASRED  to  model  blast  injuries  is  currently  not  being  used  so  this  last 
number  is  normally  entered  as  (0.000). 

3.  A  maximum  of  seven  weight  classes  or  fragment  numbers  can  be  written  on  any  one  line.  If  the 
number  of  weight  classes  in  an  angular  segment  exceeds  seven,  then  additional  lines  of  weight  class 
and  additional  lines  of  fragment  numbers  must  be  used.  For  example,  if  the  last  number  in  the 
angular  segment  head  files  list  19  weight  classes,  then  there  will  be  three  lines  of  weight  classes 
followed  by  three  lines  of  fragment  numbers.  The  first  two  lines  of  weight  class  will  contain  seven 
class  each  and  the  third  line  will  contain  five.  The  fourth  and  fifth  lines  following  the  header  will 
contain  seven  fragment  numbers  each.  The  sixth  line  will  again  contain  five  numbers.  If  the 
number  of  weight  classes  is  smaller  than  seven,  there  will  be  a  single  line  of  weight  class  and  single 
line  of  fragment  numbers.  The  entries  on  the  line  will  equal  the  actual  number  of  weight  classes. 

4.  The  configuration  tracking  data  are  appended  to  the  Z-data  file  as  additional  information.  This 
includes  the  date  and  time  of  the  translation,  the  name  of  the  input  file,  the  output  (Z-data)  file,  and 
who  created  the  file.  Additionally,  the  configuration  parameters  used  to  convert  the  file  are  append¬ 
ed.  These  configuration  parameters  are  appended  in  .csv  format  so  that  they  can  actually  be  used 
verbatim  as  the  configuration  file  for  future  translations.  All  this  appended  information  is  ignored 
by  CASRED  because  the  FORTRAN  code  stops  reading  before  this  appended  section.  Figure  9 
displays  the  first  part  of  the  Z-data  output  file  that  was  translated  from  the  input  shown  in  figure  5. 


Session  Edit  View  Bookmarks  Settings 

Help 

unclassified 
New  Grenade 
zdata 
0.000 

36 . 000| 
5.000 

2.500 

0.000 

0.000 

0.000 

1.000 

1.000 

0.000 

5.000 

10.000 

7.500 

0.000 

0.000 

0.000 

1.000 

1.000 

0.000 

10.000 

15.000 

12.500 

0.000 

0.000 

0.000 

1.000 

1.000 

0.000 

15.000 

20.000 

17.500 

0.000 

0.000 

1293. 554 

1.000 

1.000 

0.000 

20.000 

25.000 

22.500 

1293.554 

2587.108 

2570.712 

2.000 

1.550 

0.027 

n  r  r\r\r\ 

1.650 

0.037 

•~%e\  r\r\r\ 

n  t  rnn 

n  nn  “Tin 

n  r  r  a  m  *r 

orro  rn  n 

1  A  AAA 

Figure  9.  A  Z-data  file  after  a  successful  translation  (a  fixed  length  ASCII  record  format). 
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Comparing  the  .csv  input  in  figure  5  with  translated  output  in  figure  9,  we  note  that  the  first  four 
angular  segments  (rows  3  through  6  in  figure  5)  contained  no  weight  class,  but  by  conversion 
rule  l,  one  “empty”  weight  class  has  been  added  for  each  of  these  segments  in  the  Z-data  file. 


6.  CsvtoZdata  Configuration  File  and  Parameters 


The  configuration  file  may  be  used  to  tailor  translation  options  and  change  the  default  units  in 
the  translated  output.  Default  unit  measurements  found  in  the  fragmentation  profile  are  listed  in 
table  1. 

Table  1.  Default  units  of  measure. 


Measure 

Units 

Unit  Conversion  Factor 
(found  in  the  Csv  to  Zdata  configuration  file) 

Angles 

degrees 

CONVERSIONFACTORANGLES 

Mass 

grains 

CON  VERSIONF  ACTOR MAS  S 

Velocity 

feet  per  second 

CONVERSIONFACTORVELOCITY 

The  configuration  file  is  a  .csv  text  file  and  may  be  edited  with  a  standard  text  editor  or  a  spread¬ 
sheet.  The  sample  file  shown  in  figure  10  is  displayed  with  a  spreadsheet.  This  configuration  file 
contains  a  series  of  parameter  names  and  their  values.  Parameter  names  may  appear  in  any  order. 
The  parameters  and  their  effects  are  explained.  Parameters  not  appearing  in  the  configuration  file 
take  default  values. 


A 

B 

C 

i 

ParamName 

ParamValue 

Comment 

2 

MUNITIONNAME 

New  Grenade 

name  of  the  munition 

3 

CLASSIFICATIONNAME 

unclassified 

security  classification  of  this  information 

4 

OUTPUT  FORMAT  NAME 

zdata 

should  not  be  changed:  output  format  name 

5 

OUTPUT  FORMAT  NUMERIC  FIXED 

%1 0. 3f 

should  not  be  changed:  Defines  the  fixed  field  length  of  the  output  values 

6 

SHAPING_FACTOR_CONVERT 

0 

can  be  one  of :  0,1 ,2.  Meaning  of  each  [0:  no  change],  [1 :  convert  from 
( (ft A2)  (grainA(1/3))  )/lbs)  to  (grains/inA3)  ],  [2:  inverse  of  1] 

7 

CONVERSION  FACTOR  ANGLES 

1 

May  be  used  to  convert  angular  units.  Default  angles  are  in  degrees. 

8 

CONVERSION  FACTOR  VELOCITY 

1 

May  be  used  to  convert  velocity  units.  Default  velocity  is  ft/sec. 

9 

CONVERSI ONFACT  ORMASS 

1 

May  be  used  to  convert  mass  units.  Default  mass  are  grains. 

Figure  10.  Csv  to  Zdata  configuration  file.  (The  header  row  and  comments  column  are  both  ignored.) 


6.1  MunitionName 

This  is  a  text  field  to  identify  the  munition.  It  has  no  effect  other  than  being  echoed  in  the  output 
file  (seen  on  the  second  line  of  figure  10. 
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6.2  ClassificationName 

This  is  a  text  field  to  identify  the  security  classification  of  the  data.  It  has  no  effect  other  than 
being  echoed  in  the  output  file  (seen  on  the  first  line  of  figure  10.  This  is  not  intended  to 
conform  to  classified  information  markings  as  required  by  U.S.  Army  regulations. 

6.3  OutputFormatName 

This  parameter  identifies  the  output  format  scheme;  “zdata”  is  used  here.  This  field  is  ignored 
by  the  FORTRAN  code. 

6.4  OutputFormatNumericFixed 

This  value  (10.3F)  should  definitely  not  be  changed  since  the  FORTRAN  READ  statements  are 
expecting  fixed  length  floating  point  fields  of  10  digits  with  three  decimal  places. 

6.5  ShapingFactorConvert 

The  shaping  factor  conversion  flag:  By  default,  the  shaping  factor  is  in  (A)  square  feet  one  third 
power  grains  per  pound  {[(ft2)  (grain*  l/3))]/lb} .  This  may  be  optionally  converted  to  (B)  grains  per 
cubic  inches  (grains/in  ).  If  this  flag  is  set  to  0,  then  no  conversion  occurs  to  the  shaping  factor.  If 
this  flag  is  set  to  1,  it  will  convert  the  shaping  factor  value  from  (A)  to  (B)  units.  If  this  flag  is  set 
to  2,  it  will  convert  from  (B)  to  (A)  units. 

6.6  ConversionFactorAngles 

By  default,  angles  are  in  degrees.  All  angular  measures  written  to  the  translated  output  are 
multiplied  by  CONVERSION  FACTOR  ANGLES.  Thus,  if  the  spreadsheet  angle  is  in  degrees, 
leave  CONVERSION  FACTOR  ANGLES  set  to  1.0.  On  the  other  hand  if  the  data  in  the  spread¬ 
sheet  are  in  radians,  set  CONVERSION_FACTOR_ANGLES  to  57.295777951  and  convert  to 
degrees  (i.e.,  180  degrees/  n  radians). 

6.7  ConversionFactorVelocity 

By  default,  velocity  is  feet  per  second.  All  velocity  measurements  written  to  the  translated  output 
are  multiplied  by  CONVERSION  FACTOR  VELOCITY.  Leaving  CONVERSION_FACTOR_ 
VELOCITY  set  to  1 .0  will  keep  the  default  feet-per-seconds  units.  If  the  spreadsheet  uses  meters 
per  second  for  fragment  velocities,  convert  these  velocities  to  feet  per  second  by  using  a 
CONVERSION  FACTOR  VELOCITY  equal  to  3.2800840. 

6.8  ConversionFactorMass 

By  default,  mass  is  in  grains.  All  mass  measurements  written  to  the  translated  output  are  multiplied 
by  CONVERSION_FACTOR_MASS.  If  the  spreadsheet  uses  grains  for  fragment  weight,  leave 
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CONVERSIONFACTORMASS  set  to  1.0.  If  the  spreadsheet  uses  kilograms  for  fragment 
weight,  convert  to  grains  by  using  a  CONVERSION_FACTOR_MASS  of  15432.3583529  and  if 
the  spreadsheet  fragment  weights  are  in  grams,  use  15.432358. 


7.  Summary 


CASRED  is  a  computer  model  that  computes  probability  of  incapacitation  as  a  result  of  a  round 
or  fragment  impact  for  an  individual  (human)  target  with  or  without  ballistic  protection.  For 
fragment  threats,  CASRED  requires  a  description  of  the  fragment  masses,  velocities,  and 
distribution  densities.  These  fragment  patterns  can  be  described  as  an  ASCII  file  in  Z-data 
format  or  as  spreadsheet  in  JMEM  (Joint  Munitions  Effectiveness  Manual)  format. 
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Appendix  A.  Comma-Separated  Values  (CSV)  Library 


This  appendix  describes  the  interface  functions  of  the  library  used  to  parse  the  CSV  records.  The 
library  is  known  as  the  comma-delineated  field  (cdf),  first  published  in  1999  ( 4 ).  Since  then,  a 
practical  specification  has  been  published  standardizing  the  CSV  format  (2).  In  particular,  this 
CSV  specification  clarifies  the  literal  quote  character  that  was  ambiguous  in  1999. 

Functions 

•  char  *  cdf_strtok  (char  *str,  int  *flag,  int  litteral) 

•  int  edf_scan_fields  (char  *fields[],  int  num_fields,  char  *buffer,  int  *cdfflag) 

Function  Descriptions 


•  int  cdf_scan  fields  (char  *  fields!  ]>  int  num  fields,  char  *  buffer,  int  *  cdfflag) 


~  cdf_scan_f ields ( ) 

* 

*  int  cdf_scan_f ields (char  *f ields [], int  num_f ields, char*buffer, int  *cdfflag) 
*■ 

*  cdf_scan_f ields ( )  scans  the  comma  separated  fields  found  in  "buffer" 

*  the  first  "num_fields"  fields  are  read  and 

*  malloc'd  duplicates  of  these  strings  are  returned 

*  in  the  array  "char  *fields[]". 

* 

* 

*  Returns  0  on  error. 

*  Otherwise  the  number  of  fields  read  and  returned  in  "fields []" 

*  is  returned. 

*  if  a  quoted  comma  separated  field  ends  prematurely, 

*  then  -1  is  returned  in  cdfflag. 


•  char*  cdf_strtok  (char  *  str,  int  *  flag,  int  litteral) 


~  cdf_strtok() 

* 

*  char  *cdf_strtok(  char  *str  ,  int  *flag,  int  literal  ); 

* 

*  Similar  to  strtok(3)  but  specialized  for  comma-delimited  fields. 

*  cdf_strtok()  reads  and  returns  pointers  to  the  comma  separated 

*  field (s)  within  the  string  "str".  The  returned  string  will  be 

*  the  characters  found  between  field  separators  (the  comma) . 

*  [Note:  If  the  field  is  empty,  (e.g.  ",,"  then  an  empty  string 

*  would  be  returned  (i.e.  "")]. 

* 

*  Subsequent  calls  will  (with  str=NULL)  will  return  subsequent 

*  comma-dilimated  fields  in  the  original  string  until  no  more 

*  fields  are  found,  (and  a  NULL  is  then  returned) . 

* 

* 

*  flag  is  set  to  -1  if  the  field  ended 

*  before  a  comma  or  newline  was  found  (this  can  only  occur 

*  in  the  case  of  a  string  field.  (A  quoted  string  field) . 
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That  is  when  (")  is  the  first  character  in  a  field, 
(then  we  expect  a  string  field) 
in  which  case  the  string  contents  is  read 
and  the  whole  field  content  is  return 
(including  the  enclosing  quotes  ("). 


literal 

Within  a  string  field  the  quote  character  (") 
can  be  quoted  by  placing  a  the  literal  character 
directly  in  front  of  the  quote  character 
Many  databases  may  used  the  quote  ' " ' 

(e.g.  "This  is  a  string  with  ""quotes""") 
Also  the  literal  character  is  often  the  backslash 
(e.g.  "This  is  a  string  with  VquotesV") 


W 


Geoff  Sauerborn 
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